This guide shows you how to write a scientific article using the LaTeX document preparation and markup system. We emphasize typing commands at the unix command line in this guide as a way for reader to see what is happening under the hood of the LaTeX engine and thus gain flexibility and power over the production of their own academic documents. We provide some links to graphical interfaces to LaTeX at the end of the document.

To help people practice these commands we have a Jupyter Lab instance available within which you can start a Terminal session so that you can type the commands required to build a publication quality pdf from a LaTeX file. You can start this environment here.

1 The structure of a document

A LaTeX document (or a .tex file) is a plain text document that contains commands that tell a processing program how to create a beautiful pdf. This figure shows a whole LaTeX document and explains at a high level what the parts of the document do.

The Structure of a LaTeX document

After processing that document (via, say, the command latexmk -pdflatex example.tex, assuming that the document is called example.tex), one can see a pdf file like the following image:

The associated pdf document

1.1 Practice:

What does example.tex look like when compiled to a pdf document? Can you add a title or author? You can practice by looking at the directory 1_structure in the Jupyter Lab window that launches when you clink on launch binder from the README.md file in the the associated github repository and then clicking on the Terminal icon in the Jupyter Lab pane. Once you are there, try typing latexmk -pdflatex example.tex and then looking at the pdf. (Try out \title{} and \author{} in the preamble and \maketitle just after the \begin{document} line.)

You can also copy the github repository to your own local machine and launch the Terminal to see a Unix command prompt if you are using a Mac or Linux machine. Windows machine also offer a unix command prompt, but it is a bit more involved to install it.

2 Flavors and Programs: tex, latex, pdflatex, etc …

A “LaTeX document” is short-hand for a plain text document written with markup like \textbf{this is bold} for bold text or $\alpha + \beta \frac{1}{x^2}$ for math like \(\alpha + \beta \frac{1}{x^2}\). Once you have a plain text document with markup, you then process it using a set of programs to create a publishable output like a .pdf or .html file.

Although the most basic program that parses such markup is called tex, in current daily use, you will mostly find yourself using pdflatex or xelatex or maybe lualatex.

For example, at the Unix command prompt in the Terminal, you might type pdflatex example.tex to be

When Donald Knuth created this approach to making beautiful scientific documents, he started with the tex program but Leslie Lamport build latex by combining multiple tex commands into fewer and simpler macros. Both originally created documents in dvi or postscript format. Nowaways, pdf files are the best way to convey a document from one person to another such that the visual formatting stays the same.

Here is a list of the common programs that one might use to create a pdf file from a latex document:

Two take-aways:

Notice also:

The following figure shows how it may require three runs of pdflatex (plus a run of bibtex) to go from an example.tex file to an example.pdf file:

From LaTeX to PDF commands

You can replace those multiple lines with a single call to latexmk example.tex.

2.1 Practice

See the directory 2_texflavors and the readme.md file therein.

3 3. LaTeX workflows

Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.

paper_topic_name                       | string used for repo, tex, and bib files
+   requirements.txt                   | number of pages,  etc
+-- 1_submitted_paper
|   +-- paper_topic_name.tex
|   +-- refs_topic_name.bib
|   +-- journal_class.cls              | any files needed for the journal latex style
|   +-- figures
|   |   +-- temp_vs_time.pdf           | descriptive names for figures (not fig1.pdf, etc)
|   |   +-- error_vs_stepsize.pdf
|   |   `-- ...
|   +-- data                           | data files that generate the figures
|   |   +-- Makefile                   | Makefile that will re-generate all figures
|   |   +-- temp_vs_time.csv           | use the same name as the resulting figure
|   |   +-- plot_temp_vs_time.py       | plotting scripts, use names like plot_.py
|   |   `-- ...
|   `-- submitted_paper_topic_name.pdf | actual PDF file submitted
+-- 2_reviews
|   +-- review_1.pdf                   | individual reviews
|   +-- review_2.pdf
|   `-- editor_statement.pdf           | instructions and summary from editor
+-- 3_response_to_reviews
|   +-- response_topic_name.tex
|   `-- sent_response_topic_name.pdf   | actual PDF file sent to editor
`-- 4_revised_paper
    +-- paper_topic_name_revised.tex
    +-- refs_topic_name_revised.bib
    +-- journal_class.cls              | copy here any other files needed
    +-- figures                        | copy here all the figures again
    |   +-- temp_vs_time.pdf           | edit figures as needed
    |   +-- error_vs_stepsize.pdf
    |   `-- ...
    +-- data                           | copy all data again and edit as needed
    |   `-- ...
    `-- submitted_paper_topic_name_revised.pdf | actual PDF submitted

Reference: Matt West @ https://lagrange.mechse.illinois.edu/latex_quick_ref/

3.1 Practice

See the directory 3_workflows and the readme.md file therein.

4 git version control: Use it!

What to track:

What not to track:

Tips:

Commit often

For large edits, take sections at a time, to reduce merge conflicts

4.1 Practice

See the directory 4_git and the readme.md file therein.

5 5. Journal Style

The journal will have a style file

Example: https://www.siam.org/publications/journals/about-siam-journals/information-for-authors#dnn_ctr2112_ContentPane

Example: https://www.siam.org/Portals/0/Publications/Journals/stylemanual/SIAM_STYLE_GUIDE_2019.pdf

Following both of these will speed up the review and copy editing.

5.1 Practice

See the directory 5_style and the readme.md file therein.

6 On Writing: An interlude…

grep TODO paper_randnoise.tex

Remember: Peer reviewed publications are critically important to science — treat your writing and presentation of results with care

Remember: Peer reviewed publications take reviewer/editor time — treat your writing and presentation of results with care

Remember: (Hopefully) Many people will read your publication — treat your publication with care

6.1 Practice

See the directory 6_linting and the readme.md file therein.

7 LaTeX dos and don’ts: Fact, not opinion! :)

DO keep your LaTeX readable!

DON’T overuse macros

DO attach a float environment after the paragraph of first reference

DON’T use \FloatBarrier and other tricks like \newpage, \vspace or \hspace for spacing

DO use packages for consistent layouts

DON’T use align for everything

DO use consistent fonts throughout (more on this…)

7.1 Practice

See the directory 7_dos and the readme.md file therein.

8 8. On bibtex

The journal .bst defines the required fields

General workflow:

The Structure of a LaTeX document with BIB

8.1 Practice

See the directory 8_citations and the readme.md file therein.

9 On Figures

Fonts in figures should match the fonts in the float/article.

\includegraphics[width=0.3textwidth]{./figures/myfig.pdf} also scales the fonts – be careful to ensure your figure text is easy to read.

Use consistent color schemes throughout the paper

Label everything

Do not introduce new notation in a figure or its caption

The figure caption should describe, not discuss.

A terrible figure

9.1 Practice

See the directory 9_figures and the readme.md file therein.

10 Helpful tools

tikz: sharp figures and schematics in LaTeX

tikzpdf: build/rebuild tikzpictures

latexrun: compile and summarize warnings

chktex: a LaTeX linter

betterbib: automatically format/update your bib entries

illinois-letterhead: a letterhead in LaTeX

scrub your LaTeX and submit to Arxiv:

booktabs: nice looking tables

siunitx: nice looking numbers and units

algorithm2e: algorithm environment

cleveref: \cref{} referencing for all

hyperref: hyper linkes to figures, etc

backref: add page numbers to the bib

microtype: http://www.khirevich.com/latex/microtype/

enumitem: full control of itemize environments

11 Collaborate Asynchronously using Github

See

On commit messages

12 Collaborate Synchronously using…

There are several tools that allow collaborators to edit plain text documents at the same time.

Some like Overleaf because it compiles LaTeX.

Others like Teletype for Atom.

Or Hedgedoc

Or Hack MD

Or TeXPad Connect

13 Extra:

Before you commit and send it to collaborators you need to do a clean recompile at the command line.

13.1 Ways to type a document using LaTeX markup

A LaTeX document is a plain text file. This means that you can use any text editor to write a LaTeX document. However, a text editor that (1) recognizes that \textbf{} is a LaTeX command or that (2) keeps track of matching braces and parentheses makes it easier to write LaTeX markup. To that end, we use neovim with vimtex plugins but we know that there are many other approaches to typing a plain text document using LaTeX markup.

Our friends who use LaTeX like the following systems. Each person prefers to interact with their computer differently, so we merely list what we’ve heard about here.

  • Emacs with Auctex
  • [Neovim or Vim with vimtex or texlab]
  • TexPad (we think this hides too many errors and warnings, so we think this is most useful so that you can go back to the command line)
  • TexShop (we think this hides too many errors and warnings, so we think this is most useful so that you can go back to the command line)
  • [TeXstudio]
  • [Atom]
  • [Sublime 3]

13.2 Information about this document

We wrote this document using pandoc flavored markdown and turned it from plain text into HTML via the following command at the unix command line on our OS X laptops:

pandoc --css latex-guide.css --standalone -N  --from=markdown+yaml_metadata_block -V date="Version of $(date +%Y-%b-%d%n)" latex-guide.md -o latex-guide.html

14 References